feat: x402BatchSettlement contract by CarsonRoscoe · Pull Request #1950 · x402-foundation/x402

CarsonRoscoe · 2026-04-07T02:41:42Z

Description

Implements x402BatchSettlement, the onchain escrow contract powering the batch-settlement x402 payment scheme. This scheme is designed for high-frequency API access, clients pre-fund a subchannel, sign off-chain cumulative vouchers per request, and the server batch-claims them onchain at its discretion. No per-request gas cost.

Deployed to Base Sepolia (0x40200e6f073aCB938e0Cf766B83f4E5286E60003) for parallel SDK development.

Contract Overview

The contract manages two layers: a service registry (one record per server) and subchannels (one per (serviceId, payer, token) triple).

Service lifecycle

Servers register a serviceId first-come-first-serve, specifying an initial payTo address, an initial authorizer, and a withdrawWindow (bounded 15 min – 30 days). Registration can be done directly or gaslessly via an EIP-712 signed registerFor. Admin operations (add/remove authorizer, update payTo, update withdraw window) are all gaslessly submittable — signed by an existing authorizer and consumed with an adminNonce to prevent replay. At least one authorizer must always remain.

Subchannel lifecycle

A subchannel is identified by (serviceId, payer, token), making services token-agnostic — any ERC-20 can be deposited. Three gasless deposit methods are supported:

EIP-3009 (receiveWithAuthorization) — ideal for USDC, fully off-chain
Permit2 (permitWitnessTransferFrom) — works for any ERC-20 with Permit2 approval, with a DepositWitness binding the deposit to a specific service
EIP-2612 + Permit2 — two signatures, one call; non-fatal permit failure falls through if approval already exists

Payment flow

Clients sign EIP-712 Voucher messages per request. Each voucher carries a monotonically increasing nonce and a cumulative cumulativeAmount. The server accumulates these off-chain and batches them into a single claim(serviceId, token, VoucherClaim[]) call. Claimed amounts accumulate in unsettled[serviceId][token] and are transferred to payTo via a separate settle(serviceId, token). The split lets servers amortize gas across arbitrarily many payers.

Voucher signature verification

Signatures are verified by pure ECDSA recovery — no EIP-1271. Smart contract wallets are supported via client signer delegation: a payer authorizes an EOA hot wallet to sign on their behalf (authorizeClientSigner / authorizeClientSignerFor). Delegation is per-service and uses a clientNonce for gasless replay protection.

Withdrawals

Three exit paths:

Cooperative (instant): Server signs an EIP-712 CooperativeWithdraw as authorizer; unclaimed deposit is refunded immediately, can batch multiple payers.
Gasless non-cooperative: Payer signs RequestWithdrawal (includes withdrawNonce to prevent replay after cooperative withdraw); facilitator submits requestWithdrawalFor. After the window, anyone calls withdraw.
Direct non-cooperative: Payer calls requestWithdrawal directly.

Both reset paths preserve the voucher nonce so old vouchers cannot be replayed after re-deposit. The withdrawNonce increments on each cooperative withdraw to prevent authorizer signature replay.

Tests

Test Results — 174/174 passed, 0 failed

Test Suite	Type	Tests	Result
`X402BatchSettlementTest`	Unit	98	✅ all pass

Coverage — Production Contracts

Contract	Lines	Statements	Branches	Functions
`x402BatchSettlement.sol`	100% (245/245)	100% (292/292)	100% (54/54)	100% (35/35)

x402BatchSettlement is the primary new contract and hits 100% on all four coverage axes

Checklist

I have formatted and linted my code
All new and existing tests pass
My commits are signed (required for merge) -- you may need to rebase if you initially pushed unsigned commits

ilikesymmetry

First pass gut says lots of code and would like to trim down and simplify where possible. Going to take more passes.

contracts/evm/src/x402BatchSettlement.sol

ilikesymmetry · 2026-04-07T04:55:44Z

Directionally, I think we should move towards more statelessness like this: https://gist.github.com/ilikesymmetry/b351bd6ca47a9419c91b195bce332952

specs/schemes/deferred/scheme_batch_settlement_evm.md

contracts/evm/src/x402BatchSettlement.sol

specs/schemes/deferred/scheme_batch_settlement_evm.md

vercel · 2026-04-09T23:15:40Z

@CarsonRoscoe is attempting to deploy a commit to the Coinbase Team on Vercel.

A member of the Team first needs to authorize it.

ilikesymmetry

Multiple security issues needing resolution before proceeding to audit!

ilikesymmetry · 2026-04-10T00:50:18Z

contracts/evm/src/x402BatchSettlement.sol

+    struct VoucherClaim {
+        Voucher voucher;
+        bytes signature;
+        uint128 claimAmount;


now that we support authorizers signing, this probably needs to be totalClaimed to protect against replays

ilikesymmetry · 2026-04-10T00:50:35Z

contracts/evm/src/x402BatchSettlement.sol

+    bytes32 public constant REFUND_TYPEHASH =
+        keccak256("Refund(bytes32 channelId)");


needs replay protection in case channel redeposited

ilikesymmetry · 2026-04-10T00:50:48Z

contracts/evm/src/x402BatchSettlement.sol

+    bytes32 public constant CLAIM_BATCH_TYPEHASH =
+        keccak256("ClaimBatch(bytes32 claimsHash)");


would prefer to have full types here as this feels like a hack

ilikesymmetry · 2026-04-10T00:51:29Z

contracts/evm/src/x402BatchSettlement.sol

+    event ChannelCreated(bytes32 indexed channelId, ChannelConfig config);
+    event Deposited(
+        bytes32 indexed channelId,
+        uint128 amount,
+        uint128 newBalance
+    );
+    event Claimed(
+        bytes32 indexed channelId,
+        uint128 claimAmount,
+        uint128 newTotalClaimed
+    );
+    event Settled(
+        address indexed receiver,
+        address indexed token,
+        uint128 amount
+    );


add msg.sender

ilikesymmetry · 2026-04-10T00:51:34Z

contracts/evm/src/x402BatchSettlement.sol

+        public receivers;
+
+    // =========================================================================
+    // Events


missing refund event

ilikesymmetry · 2026-04-10T00:57:57Z

contracts/evm/src/x402BatchSettlement.sol

+            (address recovered, ECDSA.RecoverError err, ) = ECDSA
+                .tryRecoverCalldata(digest, vc.signature);
+            if (err != ECDSA.RecoverError.NoError || recovered != payerAuth) {
+                revert InvalidSignature();
+            }


feel like we should just use recover instead of try given we just revert anyways?

ilikesymmetry · 2026-04-10T00:59:12Z

contracts/evm/src/x402BatchSettlement.sol

+    function _verifyReceiverAuthorizer(
+        bytes32 typehash,
+        bytes32 data,


don't feel like we need this function at all. Just compute digest on outer layer and do isValidSignatureNow check where we need it

ilikesymmetry · 2026-04-10T01:01:28Z

contracts/evm/src/periphery/ERC3009DepositCollector.sol

+    using SafeERC20 for IERC20;
+
+    /// @inheritdoc IDepositCollector
+    function collect(


CRITICAL: This function is permissionless and lets anyone choose the recipient, letting anyone frontrun transactions and steal funds. This needs to be bound to the BatchSettlement singleton and only forward funds there and also lock down the caller to the singleton too. Same for all other collectors and would recommend making an abstract DepositCollector for this purpose.

ilikesymmetry · 2026-04-10T01:03:05Z

contracts/evm/src/periphery/Permit2WithERC2612DepositCollector.sol

+/// @dev Enables a single-tx deposit for tokens that implement EIP-2612, without requiring the payer
+///      to have previously approved Permit2. The EIP-2612 permit call is soft-fail (try/catch) so that
+///      pre-existing approvals or replayed permits don't revert the entire deposit.
+contract Permit2WithERC2612DepositCollector is Permit2DepositCollectorBase {


feel like we should just merge this with other Permit2 collector and do a pattern like this for handling the optional 2612 approval. Would let us go down from 3->1 contracts for the use case and only add a single conditional block to the implementation. Seems net simpler.

ilikesymmetry · 2026-04-10T01:04:05Z

contracts/evm/src/x402BatchSettlement.sol

+    struct Voucher {
+        ChannelConfig channel;
+        uint128 maxClaimableAmount;
+    }


I don't love how much calldata there is here. I think there's an optimization we could make but will save it until we fix the security issues.

CarsonRoscoe added 3 commits April 6, 2026 19:31

spec: added reference spec

3854d4d

feat: added x402BatchSettlement contract

1bdf093

feat: added tests

298e965

github-actions bot added the specs Spec changes or additions label Apr 7, 2026

CarsonRoscoe changed the title ~~Feat/evm contracts batch settlement~~ feat: x402BatchSettlement contract Apr 7, 2026

feat: mining 0x4020...0003 vanity & deploy to base sepolia

465a30e

ilikesymmetry reviewed Apr 7, 2026

View reviewed changes

contracts/evm/src/x402BatchSettlement.sol Outdated Show resolved Hide resolved

CarsonRoscoe added 2 commits April 7, 2026 17:48

feat: updaded spec/contract per recommendations

f5b4307

feat: updated tests

20f47c4

phdargen self-assigned this Apr 8, 2026

phdargen reviewed Apr 8, 2026

View reviewed changes

specs/schemes/deferred/scheme_batch_settlement_evm.md Outdated Show resolved Hide resolved

phdargen reviewed Apr 8, 2026

View reviewed changes

contracts/evm/src/x402BatchSettlement.sol Outdated Show resolved Hide resolved

CarsonRoscoe added 5 commits April 8, 2026 17:59

feat: update x402BatchSettlement

646fb02

feat: add peripheral contracts

da4298b

feat: updated spec

154d733

feat: updated tests and deploy

1181bad

feat: removed extra.receiver from spec

1e9d806

phdargen reviewed Apr 9, 2026

View reviewed changes

contracts/evm/src/x402BatchSettlement.sol Outdated Show resolved Hide resolved

phdargen reviewed Apr 9, 2026

View reviewed changes

specs/schemes/deferred/scheme_batch_settlement_evm.md Outdated Show resolved Hide resolved

phdargen and others added 9 commits April 9, 2026 09:18

spec v1.2 (#44)

a1a4408

feat: added 4th deposit; renamed others

00d93b1

feat: updated tests

d768c91

feat: add collectors model

81638a4

feat: removed periphery contracts

0638e2c

feat: rename cooperativeWithdraw to refund

721145c

feat: added multicall to x402BatchSettlement for migration support

9b8f795

feat: added multichannel & migration test scenarios

cf20c25

feat: add deploy for peripery contracts

3b577ae

ilikesymmetry suggested changes Apr 10, 2026

View reviewed changes

CarsonRoscoe added 2 commits April 9, 2026 19:01

feat: pr feedback

aaa5ef7

feat: pr review feedback

b84cd24

		bytes32 public constant REFUND_TYPEHASH =
		keccak256("Refund(bytes32 channelId)");

		bytes32 public constant CLAIM_BATCH_TYPEHASH =
		keccak256("ClaimBatch(bytes32 claimsHash)");

Conversation

CarsonRoscoe commented Apr 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Contract Overview

Tests

Test Results — 174/174 passed, 0 failed

Coverage — Production Contracts

Checklist

Uh oh!

ilikesymmetry left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ilikesymmetry commented Apr 7, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

vercel bot commented Apr 9, 2026

Uh oh!

ilikesymmetry left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

CarsonRoscoe commented Apr 7, 2026 •

edited

Loading